// buzzer.h 完整注释版
#ifndef __BUZZER_H
#define __BUZZER_H

#include "main.h"

/**​
 * @brief 蜂鸣器音效类型枚举
 * 
 * 预定义的蜂鸣模式：
 * - BEEP_ALARM     报警音（急促短鸣循环）
 * - BEEP_NOTICE    通知音（长鸣单次） 
 * - BEEP_SHORT_BEEP 短促提示音
 * - BEEP_ERROR     错误提示音（双短鸣循环）
 */
typedef enum {
    BEEP_ALARM,
    BEEP_NOTICE,
    BEEP_SHORT_BEEP,
    BEEP_ERROR,
    BEEP_TYPE_COUNT  // 类型总数，用于参数校验
} BeepType;

/**​
 * @brief 蜂鸣器初始化
 * 
 * 初始化PA15引脚为GPIO输出模式，默认关闭蜂鸣器
 * @note 必须在其他函数之前调用一次
 */
void Buzzer_Init(void);

/**​
 * @brief 启动蜂鸣音效
 * 
 * @param type 音效类型，从BeepType枚举中选择
 * @note 新音效会立即覆盖当前播放
 */
void Buzzer_StartBeep(BeepType type);

/**​
 * @brief 立即停止蜂鸣
 * 
 * 终止当前播放，将引脚置为低电平
 */
void Buzzer_StopBeep(void);

/**​
 * @brief 蜂鸣器驱动更新函数
 * 
 * 必须在系统每10ms周期调用一次，用于时序控制
 * @warning 必须确保精确的10ms调用间隔
 */
void Buzzer_Update10ms(void);

#endif

/* 使用方法：
// 在main.c中包含头文件
#include "buzzer.h"

// 系统初始化时调用（一次）
Buzzer_Init();

// 触发报警音（循环播放）
Buzzer_StartBeep(BEEP_ALARM);

// 在定时器中断中调用更新函数（推荐方式）
void TIMx_IRQHandler(void) {
    if (__HAL_TIM_GET_IT_SOURCE(&htimx, TIM_IT_UPDATE)) {
        Buzzer_Update10ms();
        __HAL_TIM_CLEAR_IT(&htimx, TIM_IT_UPDATE);
    }
}

// 或主循环中调用（需确保10ms间隔）
while(1) {
    Buzzer_Update10ms();
    HAL_Delay(10);  // 非精确方式，仅用于测试
}

// 停止所有声音
Buzzer_StopBeep();
*/

/* 扩展说明：
1. 添加自定义音效步骤：
   a. 在BeepType枚举中新增类型
   b. 在buzzer.c中定义对应的BeepStep数组
   c. 在patterns数组中配置参数

2. 示例：添加开机音乐
typedef enum {
    // ...原有类型
    BEEP_START_UP,
    BEEP_TYPE_COUNT
} BeepType;

// buzzer.c中添加：
static const BeepStep startup_steps[] = {
    {1, 5}, {0, 2},  // 短鸣
    {1, 5}, {0, 2},  // 短鸣
    {1, 20}, {0, 5}  // 长鸣
};

static const BeepPattern patterns[] = {
    // ...原有配置
    [BEEP_START_UP] = {startup_steps, 4, false}
};

// 使用：
Buzzer_StartBeep(BEEP_START_UP);
*/

/* 注意事项：
1. 蜂鸣器有效电平取决于硬件连接方式，可通过反转level值修改
2. 调用Buzzer_Update10ms()的时序精度直接影响音效时长
3. 多个音效同时调用时，后调用的会覆盖前一个
4. 长时间阻塞主循环会导致蜂鸣器时序异常
*/